%==========================================================================
%=  This file is part of the Sound Restoration Project
%=  (c) Copyright Industrial Mathematics Institute
%=                University of South Carolina, Department of Mathematics
%=  ALL RIGHTS RESERVED
%=
%=  Author: Borislav Karaivanov
%==========================================================================

%==========================================================================
% List of the files on which this procedure depends:
%
% none
%
%==========================================================================

%==========================================================================
% The function "visualizeOverlapGuess" visualizes the search for the best
% overlap guess.
% INPUT: "countArr" is a column vector of length equal to the number of
% allowed overlaps. Each of its entries holds the number of pair of signals
% having a local minimum of the relative difference for the overlap
% corresponding to that entry.
% "relDiffArr" is a 2D array whose rows hold the relative differences for
% the pairs of signals over all allowed overlaps. It has as many rows as
% there are pairs of signals, and as many columns as there are allowed
% overlaps.
% "isLocalMinArr" is a 2D boolean array of the same size as "relDiffArr".
% Each of its rows correspond to a single pair of signals. Each entry in a
% row indicates whether or not for the corresponding overlap the pair of
% signals associated with that row has a local minimum of its relative
% difference.
% "numToUse" is a positive integer specifying how many pairs of consecutive
% signals are used to generate the visualized overlap guess.
% "locMinNbhdRad" is a positive integer specifying the radius of the
% interval around a sample where values of a function are checked in order
% to determine if it has a local minimum at this sample. More precisely,
% the function is considered to have a local minimum at the sample if all
% function values in the said interval are not smaller than the value at
% the central sample.
% "mostPopularOverlap" is the most popular among the overlaps at which the
% relative difference of any pair of consecutive signals has a local
% minimum.
% "percentPopularity" is the percentage of pairs of consecutive signals
% for which relative difference has a local minimum at the most popular
% overlap.
% "secondMostPopularOverlap" is the second most popular among the overlaps
% at which the relative difference of any pair of consecutive signals has a
% local minimum.
% "percentPopularityOfSecond" is the percentage of pairs of consecutive
% signals for which relative difference has a local minimum at the second
% most popular overlap.
% OUTPUT: None.
%==========================================================================
function visualizeOverlapGuess(countArr, relDiffArr, isLocalMinArr, ...
    numToUse, locMinNbhdRad, mostPopularOverlap, percentPopularity, ...
    secondMostPopularOverlap, percentPopularityOfSecond)

% Use the existing global variables to determine whether visualization is
% required, and what common prefix and file extension are to be used for
% the names of the image files saving snapshots of figures.
global globalDoVisualize globalShotFileNamePrefix globalShotFileExt
if (globalDoVisualize ~= true)
    return;
else
    shotFileNamePrefix = globalShotFileNamePrefix;
    shotFileExt = globalShotFileExt;
end

% Compose the current common prefix.
commonPrefix = [shotFileNamePrefix 'SndUsed' num2str(numToUse) '_LocMinRad' num2str(locMinNbhdRad)];

% Find the overlaps with the top 10 counts.
[sortedArr, origIndArr] = sort(countArr, 'descend');

% Compute the average relative average difference over all pairs having a
% local minimum of the relative average difference at any particular
% overlap.
diffArr = mean(relDiffArr.*isLocalMinArr);

% Print the overlaps with top counts, their counts, and average relative
% differences over all pairs having a local minimum of the relative
% difference at those particular overlaps.
numTopCountsToShow = 10;
fprintf(1, 'Top %d overlaps with ranking and average difference: ', numTopCountsToShow);
fprintf(1, '(%d,%d,%.4f) ', [origIndArr(1:numTopCountsToShow); sortedArr(1:numTopCountsToShow); diffArr(origIndArr(1:numTopCountsToShow))]);
fprintf(1, '\n');

fprintf(1, ['best overlap guess: ' num2str(mostPopularOverlap) '\n']);
fprintf(1, ['percent popularity of best overlap guess: ' num2str(percentPopularity, '%.2f') ' %% \n']);
fprintf(1, ['second best overlap guess: ' num2str(secondMostPopularOverlap) '\n']);
fprintf(1, ['percent popularity of second best overlap guess: ' num2str(percentPopularityOfSecond, '%.2f') ' %% \n']);
fprintf(1, ['percent second best overlap guess is weaker: ' num2str(100*(percentPopularity - percentPopularityOfSecond)/percentPopularity) ' %% \n']);

% Plot the counts of all allowed overlaps.
figHandle = figure;
plot(countArr);
xlabel('overlap');
ylabel('number of signals with local min at this overlap');
title('Most popular overlap');
axis([1 numel(countArr) 0 (max(countArr) + 1)]);
% Maximize the figure to cover the whole screen.
set(figHandle, 'Position', get(0, 'ScreenSize'));
% Save a snapshot.
shotFileName = [commonPrefix '_OverlapGuess.' shotFileExt];
print(gcf, ['-d' shotFileExt], shotFileName);
% Close the figure.
close(figHandle);

return;
% end of the function "visualizeOverlapGuess"
